Repository navigation
feat(unstable-v2): add background work to v2 - #2738
Merged
Merged
Conversation
Implement phase 1 of the v2 Background Work RFD in the v2 schema: - `ToolCallStatus::Paused`, and a broader `pending` definition that covers scheduled work - `capabilities` on `ToolCallUpdate` and `TerminalUpdate`, with an opt-in `cancel` capability following the subagent capability pattern - `tool_call/cancel` and `terminal/cancel` client-to-agent requests - a `background` list on the `running`, `requires_action`, `idle`, and (with `unstable_subagents`) `unknown` state snapshots, made of `terminal`, `tool_call`, and `subagent` items plus a fallback for custom items that rejects known discriminators; a malformed list is treated as not reported Document background work, the new status, both cancel methods, and the narrower `session/cancel` permission rule in the v2 prompt lifecycle, tool calls, cancellation, session setup, and migration pages and their draft copies, and note the change in the subagents and v2 overview RFDs.
…erns - Add `StateUpdate::background()` so callers can read the list without matching on each state - Rename `ToolCallCancelCapability` and `TerminalCancelCapability` to `*CancelCapabilities`, matching every other capability type including `SessionCancelCapabilities` - Reword the capability docs, which the Client acts on rather than only displays, and rewrap the cancel request docs - Note in the migration guide that terminals have one opt-in control, `terminal/cancel`
Merged
benbrandt
added a commit
that referenced
this pull request
Nov 2, 2026
…FD (#2743) * docs(schema): restore the v1 meaning of Implementation.title and the tool-call intro The plain-language pass (#2730) changed two v1 passages beyond wording: - `Implementation.title` said it "should be readable by people", which adds a should-statement to the stable v1 spec and schema. Restore the v1.14.0 meaning ("optimized to be human-readable and easily understood") without the em dash. The v2 copy uses the same text. - The v1 tool-calls intro said Agents may use Client capabilities "while running a tool call", which reads as a new timing limit. Drop the temporal clause and keep the original "or". Co-Authored-By: Claude <noreply@anthropic.com> * docs(protocol): align v2 session/cancel text with the background-work rules #2738 narrowed `session/cancel` so listed background work keeps running and its permission requests stay open, but several v2 passages still stated the old rule. Update them in the stable and draft pages and the v2 schema: - prompt-lifecycle: add the missing "or" in the announce-before-listing rule (stable only, the draft already had it), scope "stop all tool call invocations" to the cancelled foreground work, put the `-32800` rule next to the prompts it covers, and state that a `subject` the Client does not recognize, such as a custom subject type, is answered with `cancelled`. - tool-calls, cancellation, migration: answer pending permission requests for the cancelled foreground work, not every request in the session. - Schema: `RequestPermissionOutcome::Cancelled`, the `session/request_permission` request and the `session/cancel` notification descriptions now state the narrowed rule and the custom subject case. Co-Authored-By: Claude <noreply@anthropic.com> * docs(unstable): reconcile session/status, auth/status and session/set_title with their RFDs - session/status: keep `-32002` for sessions the Agent does not know, and state the RFD's exception in the schema, the draft error pages and the RFD's own error rule: an Agent that cannot cheaply tell a saved session from an unknown one may return `saved`, and the later resume or load gets `-32002`. - auth/status: add it to the draft v2 list of requests that do not fail with `auth_required`, and put the RFD's MUST NOT in the schema. - session/set_title: refusing a session the Agent cannot safely update returns `-32602`, as an explicit exception to retitling any listed session, in the schema, the draft error pages and the RFD. Co-Authored-By: Claude <noreply@anthropic.com> * docs(rfd): resolve proxy-chains ambiguities and match the reference conductor Define, in the proxy-chains RFD and the proxy schema descriptions: - Errors the conductor returns itself (before initialization, failed chain start, `proxy/initialize` from outside, misplaced `proxy/successor`, malformed envelopes, a component that exited), separate from the pass-through rule for wrapped results. - Hop-local cancellation: `$/cancel_request` names a request on its own connection, is never forwarded, and each hop re-issues it. - Envelope `_meta` is hop-local and not copied into the unwrapped message. - Version selection along the chain, the proxy's obligation to forward `initialize` before answering, the proxy/initialize result built from the successor's (same `protocolVersion`), and repeated `proxy/initialize`. - "Unchanged" results and errors mean the same JSON value. - Wrapped `params` is an object, an array, or `null`. - Forwarding of unknown requests and notifications and where `-32601` comes from. Also link version negotiation for v1 and v2, replace the old `sacp-conductor` name, drop crash-handling claims the reference conductor does not implement, and add a revision-history entry. Co-Authored-By: Claude <noreply@anthropic.com> * docs(unstable): drop the saved-for-unknown and retitle-refusal exceptions Co-Authored-By: Claude <noreply@anthropic.com> * docs(protocol): let the Agent cancel permission requests on session/cancel in v2 The Agent knows which work each permission request belongs to, so on session/cancel it stops waiting for the cancelled work's requests and cancels them with $/cancel_request, as it already does for elicitations. Clients MAY answer them early. session/close cancels every pending permission request the same way. This removes the subject-based rules for which requests the Client answers. Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements phase 1 of the v2 Background Work RFD: the schema changes from its "Schema" section and the draft docs. It's v2-only, so it's covered by
unstable_protocol_v2and has no feature flag of its own. Thesubagentlist item andbackgroundon theunknownstate also needunstable_subagents.Schema
paused: a newToolCallStatusvariant. Older v2 Clients receive it through the existingOtherfallback.pendingnow means "hasn't started running yet", with scheduling as one example.capabilities: follows the subagent capability pattern (SubagentSessionCapabilities), as the RFD specifies. The types areToolCallCapabilities/ToolCallCancelCapabilitiesandTerminalCapabilities/TerminalCancelCapabilities. The RFD named the cancel types in the singular, but they're plural here to match every other capability type, includingSessionCancelCapabilities. They're display hints, so a malformed value falls back to unsupported.background:OtherBackgroundWork) rejects knowntypevalues, the same wayOtherStateUpdatedoes. A malformedterminalortool_callitem can't fall through to it.DefaultOnErrorwith no per-item skipping, so a malformed list counts as not reported rather than as an empty list.StateUpdate::background()reads the list without matching on each state. It returnsNonefor custom states.BackgroundTerminal,BackgroundToolCall,BackgroundSubagentandOtherBackgroundWork. I added a revision history entry to the RFD saying so.Docs
Each change is made in the stable v2 page and its
draft/copy. Thesubagentdetails only go in the draft copies, since only the draft pages describe subagents.prompt-lifecycle:backgroundlist and its rules, and what Clients learn from it.subject.tool-calls: thepausedstatus and its display and transition guidance, a "Cancelling tool calls" section, a "Cancelling terminals" section, and the rule that permission requests for background work reference the listed item insubject.cancellation:session/cancelonly answers permission requests for foreground work.session-setup: close stops listed work and tells the Client how to finalize it, resume restores the list after announcing each item, and (draft only) a fork starts with no background work.migration: a sentence on thebackgroundlist and the narrower cancel rule, and an update to the line saying terminals have no control semantics, since they now have opt-in cancellation.Phases 2 and 3 of the RFD (adapters and a Client implementation, then adjustments) aren't part of this PR.